[RFC] Add ChannelMonitor::get_justice_txs for simplified watchtower integration by FreeOnlineUser · Pull Request #4453 · lightningdevkit/rust-lightning

FreeOnlineUser · 2026-03-01T06:57:59Z

Draft PR for design feedback. Implements the approach @TheBlueMatt suggested in lightningdevkit/ldk-node#813 and in review of #2552: move justice tx state tracking inside ChannelMonitor so Persist implementors don't need external queues.

What this does

Adds a single method that replaces the current 3-step dance of counterparty_commitment_txs_from_update() + manual queue + sign_to_local_justice_tx():

pub struct JusticeTransaction {
    pub tx: Transaction,
    pub revoked_commitment_txid: Txid,
    pub commitment_number: u64,
}

impl ChannelMonitor {
    pub fn get_justice_txs(
        &self,
        feerate_per_kw: u64,
        destination_script: ScriptBuf,
    ) -> Vec<JusticeTransaction>;
}

Internally, ChannelMonitorImpl stores recent counterparty CommitmentTransactions (populated during update application, pruned to entries within one revocation of current). get_justice_txs checks which have revocation secrets available, builds and signs the justice tx, and returns the result.

Changes

channelmonitor.rs: new JusticeTransaction struct, latest_counterparty_commitment_txs field, TLV 39 serialization (optional, backwards-compatible), get_justice_txs() method
test_utils.rs: simplified WatchtowerPersister (removed JusticeTxData, unsigned_justice_tx_data queue, form_justice_data_from_commitment)
127 additions, 83 deletions. All existing tests pass.

Splice handling

Pruning uses commitment numbers, not entry count. During a splice, multiple entries share the same commitment number (one per funding scope) and all are retained.

Backwards compatibility

TLV 39 is optional. Old monitors load with empty vec, populated on next update.
Old nodes reading monitors written by new code skip the unknown TLV field.
Existing counterparty_commitment_txs_from_update() and sign_to_local_justice_tx() APIs unchanged.

Design questions

Looking for input on these before moving out of draft:

Signed vs unsigned return? Currently returns fully signed transactions. Returning unsigned gives callers more flexibility on fee choice at broadcast time. Preference?
HTLC outputs? This only covers to_local justice. HTLC-timeout and HTLC-success outputs on revoked commitments are not included. Worth adding here, or separate follow-up?
Feerate source? Caller provides feerate_per_kw. An alternative would be accepting a fee estimator. Any preference?
Dust filtering? If the revokeable output is dust, revokeable_output_index() returns None and the entry is skipped silently. Right behavior, or surface this to the caller?

ldk-reviews-bot · 2026-03-01T06:58:02Z

👋 Hi! This PR is now in draft status.
I'll wait to assign reviewers until you mark it as ready for review.
Just convert it out of draft status when you're ready for review!

codecov · 2026-03-01T10:09:08Z

Codecov Report

❌ Patch coverage is 92.15686% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.93%. Comparing base (ec03159) to head (034c377).
⚠️ Report is 8 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/chain/channelmonitor.rs	95.12%	0 Missing and 4 partials ⚠️
lightning/src/util/test_utils.rs	80.00%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4453      +/-   ##
==========================================
- Coverage   85.93%   85.93%   -0.01%     
==========================================
  Files         159      159              
  Lines      104693   104736      +43     
  Branches   104693   104736      +43     
==========================================
+ Hits        89972    90001      +29     
- Misses      12213    12222       +9     
- Partials     2508     2513       +5

Flag	Coverage Δ
tests	`85.93% <92.15%> (-0.01%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

TheBlueMatt · 2026-03-02T19:55:21Z

lightning/src/chain/channelmonitor.rs

+	/// Contains the current and previous counterparty commitment(s). With splicing,
+	/// there may be multiple entries per commitment number (one per funding scope).
+	/// Pruned to remove entries more than one revocation old.
+	latest_counterparty_commitment_txs: Vec<CommitmentTransaction>,


This should be in the funding scope to support splicing. Also should probably just be cur_... and prev_... to match existing API pattern rather than a vec that is max-size 2.

Moved to FundingScope as cur/prev fields. TLV 13/15 on FundingScope, 39/41 on the outer scope for backwards compat.

TheBlueMatt · 2026-03-02T20:01:35Z

lightning/src/util/test_utils.rs

-					Err(_) => break,
-				}
-			}
+		// Use the simplified get_justice_txs API


Claude loves to leave comments about how it changed the code that are totally useless - reading the code I don't care what changes claude made in the past, I care if there's something useful to know now. Probably can just drop this.

Removed, and noted for future.

TheBlueMatt · 2026-03-02T20:04:05Z

lightning/src/chain/channelmonitor.rs

+	///
+	/// Returns a list of [`JusticeTransaction`]s, each containing a fully signed
+	/// transaction and metadata about the revoked commitment it punishes.
+	pub fn get_justice_txs(


This API doesn't really make sense. There's no information on when I should call this or when the monitor "knows about" a revoked tx. We probably want to do soemthing like the old API where you can fetch revoked transactions in relation to a specific monitor update.

Replaced with sign_initial_justice_tx() for persist_new_channel and sign_justice_txs_from_update(update) for update_persisted_channel. Each is tied to a specific point in the persistence pipeline.

Adds sign_initial_justice_tx() and sign_justice_txs_from_update() to ChannelMonitor, allowing Persist implementors to obtain signed justice transactions without maintaining external state. Storage uses cur/prev counterparty commitment fields on FundingScope, matching the existing pattern and supporting splicing. Simplifies WatchtowerPersister in test_utils by removing the manual queue and signing logic. Addresses feedback from lightningdevkit/ldk-node#813 and picks up the intent of lightningdevkit#2552.

TheBlueMatt

Thanks, I think this basically looks good!

TheBlueMatt · 2026-03-09T14:47:26Z

lightning/src/chain/channelmonitor.rs

+		let mut result = Vec::new();
+		for commitment_tx in &to_sign {
+			if let Some(jtx) =
+				self.try_sign_justice_tx(commitment_tx, feerate_per_kw, destination_script.clone())


Should we also build justice transactions for all the potential HTLC transactions? I assume we can...

Added. try_sign_justice_txs now iterates nondust_htlcs() on the revoked commitment, builds a spending tx for each HTLC output, and signs with sign_justice_revoked_htlc. Witness follows the same pattern as RevokedHTLCOutput in package.rs. Dust HTLCs are skipped when fee exceeds value.

Also added test_justice_tx_htlc_from_monitor_updates which routes a payment, captures the commitment with a pending HTLC, revokes it, and verifies the watchtower gets justice txs for both to_local and the HTLC output.

TheBlueMatt · 2026-03-09T14:48:12Z

lightning/src/chain/channelmonitor.rs

+				funding.prev_counterparty_commitment_tx =
+					funding.cur_counterparty_commitment_tx.take();
+				funding.cur_counterparty_commitment_tx = Some(commitment_tx);
+			}


I assume we can/should do this?

Suggested change

}

} else {

debug_assert!(false);

}

Extends try_sign_justice_txs to also sweep HTLC outputs when a counterparty broadcasts a revoked commitment. For each non-dust HTLC, builds a spending transaction and signs it with sign_justice_revoked_htlc. Updates WatchtowerPersister to store multiple justice txs per revoked commitment (Vec<Transaction> instead of single Transaction). Addresses review feedback from TheBlueMatt on PR lightningdevkit#4453.

Verifies that WatchtowerPersister produces justice transactions for both to_local and in-flight HTLC outputs when a commitment with pending HTLCs is revoked. Checks each justice tx spends a different output and pays to the destination script.

FreeOnlineUser

Updated with both changes. API is now sign_initial_justice_txs / try_sign_justice_txs (plural) since they return a Vec covering to_local + HTLCs. WatchtowerPersister stores Vec<Transaction> per revoked txid accordingly.

FreeOnlineUser mentioned this pull request Mar 1, 2026

Watchtower support: expose channel monitor data for external watchtower implementations lightningdevkit/ldk-node#813

Open

FreeOnlineUser force-pushed the watchtower-justice-api branch 2 times, most recently from 6993e59 to d6c7903 Compare March 1, 2026 08:23

TheBlueMatt reviewed Mar 2, 2026

View reviewed changes

FreeOnlineUser force-pushed the watchtower-justice-api branch from d6c7903 to 9af37e1 Compare March 2, 2026 22:11

FreeOnlineUser force-pushed the watchtower-justice-api branch from 9af37e1 to 034c377 Compare March 2, 2026 23:38

TheBlueMatt reviewed Mar 9, 2026

View reviewed changes

FreeOnlineUser added 3 commits March 10, 2026 11:21

Assert when commitment tx doesn't match any funding scope

1d449e2

FreeOnlineUser commented Mar 10, 2026

View reviewed changes

FreeOnlineUser marked this pull request as ready for review March 10, 2026 10:56

ldk-reviews-bot requested a review from joostjager March 10, 2026 10:57

FreeOnlineUser marked this pull request as draft March 10, 2026 11:01

-			}
+			} else {
+				debug_assert!(false);
+			}

Conversation

FreeOnlineUser commented Mar 1, 2026

What this does

Changes

Splice handling

Backwards compatibility

Design questions

Uh oh!

ldk-reviews-bot commented Mar 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Mar 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TheBlueMatt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FreeOnlineUser left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ldk-reviews-bot commented Mar 1, 2026 •

edited

Loading

codecov bot commented Mar 1, 2026 •

edited

Loading